home *** CD-ROM | disk | FTP | other *** search
/ Aminet 1 (Walnut Creek) / Aminet - June 1993 [Walnut Creek].iso / aminet / biz / misc / imagefxdevkit.lha / doc / Scan.autodoc < prev    next >
Text File  |  1992-12-14  |  45KB  |  1,846 lines
  1. TABLE OF CONTENTS
  2.  
  3. scan.library/AllocBuffer
  4. scan.library/AllocChipBitMap
  5. scan.library/AllocFastBitMap
  6. scan.library/ArrangePanel
  7. scan.library/Bar
  8. scan.library/BClose
  9. scan.library/BeginBar
  10. scan.library/BFlush
  11. scan.library/BGetc
  12. scan.library/BGets
  13. scan.library/BOpen
  14. scan.library/BPutc
  15. scan.library/BPuts
  16. scan.library/BRead
  17. scan.library/BSeek
  18. scan.library/BWrite
  19. scan.library/ClearBitMap
  20. scan.library/DeleteBitMap
  21. scan.library/EasyProcess
  22. scan.library/EndBar
  23. scan.library/Error
  24. scan.library/FreeBuffer
  25. scan.library/GetBufLine
  26. scan.library/GetError
  27. scan.library/HidePanel
  28. scan.library/InitBuffer
  29. scan.library/IntegerRequest
  30. scan.library/KillBuffer
  31. scan.library/NewGetFile
  32. scan.library/ObtainBuffer
  33. scan.library/ParseCommand
  34. scan.library/PutBufLine
  35. scan.library/PutNewBufLine
  36. scan.library/RedrawArea
  37. scan.library/RedrawFull
  38. scan.library/ReleaseBuffer
  39. scan.library/ReplaceBuffer
  40. scan.library/SaveUndo
  41. scan.library/SetError
  42. scan.library/ShowPanel
  43. scan.library/ShowStatus
  44. scan.library/StringRequest
  45. scan.library/TogglePanel
  46. scan.library/VBoolRequest
  47. scan.library/VErrorf
  48. scan.library/VInfoRequest
  49. scan.library/zzzzzz
  50.  
  51.  
  52.  
  53. scan.library/AllocBuffer
  54.  
  55.     NAME
  56.         AllocBuffer - Allocate and initialize a Buffer structure.
  57.  
  58.     SYNOPSIS
  59.         buffer = AllocBuffer ( name, width, height, depth, bits, flags );
  60.         D0.L                   A0    D0.W   D1.W    D2.W   D3.W  D4.W
  61.  
  62.         struct Buffer *AllocBuffer ( char *, short, short, short,
  63.                                      short, short );
  64.  
  65.     FUNCTION
  66.         Allocate a Buffer structure, complete with image data planes.
  67.         Initializes the structure to suitable default values.
  68.  
  69.     INPUTS
  70.         name -- Name of buffer.  Currently ignored.  Use NULL.
  71.  
  72.         width -- Width of buffer in pixels.
  73.  
  74.         height -- Height of buffer in pixels.
  75.  
  76.         depth -- Depth of buffer in 8-bit planes, use 1 for a greyscale
  77.             buffer or 3 for a color buffer.
  78.  
  79.         bits -- Number of bits per plane.  Always use 8.
  80.  
  81.         flags -- Flag bits.  Set one or more of the following:
  82.  
  83.                     BUFF_DISK   - force buffer to be created on disk.
  84.                     BUFF_BRUSH  - buffer is really a brush.  (rarely needed.)
  85.                     BUFF_NOVMEM - should not use virtual memory for the buffer.
  86.  
  87.                   More often than not, you will simply want to use
  88.                   a flags value of 0.  If the buffer is too large to
  89.                   fit in memory, the user will be asked if he wants
  90.                   to use virtual memory, in which case the buffer will
  91.                   be created on disk anyway.
  92.  
  93.     RESULT
  94.         buffer --- Pointer to a properly filled-in Buffer structure,
  95.             with cleared image data space.  NULL on failure,
  96.             with a secondary result code set in the global
  97.             error.
  98.  
  99.     EXAMPLE
  100.  
  101.     NOTES
  102.  
  103.     BUGS
  104.  
  105.     SEE ALSO
  106.         scan.library/KillBuffer,scan/buf.h
  107.  
  108.  
  109. scan.library/AllocChipBitMap                     scan.library/AllocChipBitMap
  110.  
  111.     NAME
  112.         AllocChipBitMap -- Allocate a bitmap from chip memory.
  113.  
  114.     SYNOPSIS
  115.         bitmap = AllocChipBitMap ( width, height, depth );
  116.         D0.L                       D0.L   D1.L    D2.L
  117.  
  118.         struct BitMap *AllocChipBitMap ( int, int, int );
  119.  
  120.     FUNCTION
  121.         Allocate a BitMap structure and bitplanes from chip memory, suitable
  122.         for use on an Amiga display.  The bitplanes are cleared.
  123.  
  124.     INPUTS
  125.         width -- Width of the bitmap in pixels.
  126.  
  127.         height -- Height of the bitmap in pixels.
  128.  
  129.         depth -- Depth of bitmap in planes.
  130.  
  131.     RESULTS
  132.         bitmap -- Pointer to an initialized BitMap structure, ready for use.
  133.  
  134.     EXAMPLE
  135.  
  136.     NOTES
  137.         Uses the new graphics.library AllocBitMap() function under V39.
  138.  
  139.     BUGS
  140.  
  141.     SEE ALSO
  142.         scan.library/AllocFastBitMap,scan.library/DeleteBitMap
  143.  
  144.  
  145. scan.library/AllocFastBitMap                     scan.library/AllocFastBitMap
  146.  
  147.     NAME
  148.         AllocFastBitMap -- Allocate a bitmap from fast memory.
  149.  
  150.     SYNOPSIS
  151.         bitmap = AllocFastBitMap ( width, height, depth );
  152.         D0.L                       D0.L   D1.L    D2.L
  153.  
  154.         struct BitMap *AllocFastBitMap ( int, int, int );
  155.  
  156.     FUNCTION
  157.         Allocate a BitMap structure and bitplanes from fast memory.
  158.         The bitplanes are cleared.
  159.  
  160.     INPUTS
  161.         width -- Width of the bitmap in pixels.
  162.  
  163.         height -- Height of the bitmap in pixels.
  164.  
  165.         depth -- Depth of bitmap in planes.
  166.  
  167.     RESULTS
  168.         bitmap -- Pointer to an initialized BitMap structure, ready for use.
  169.  
  170.     EXAMPLE
  171.  
  172.     NOTES
  173.         Uses the new graphics.library AllocBitMap() function under V39.
  174.  
  175.     BUGS
  176.  
  177.     SEE ALSO
  178.         scan.library/AllocFastBitMap,scan.library/DeleteBitMap
  179.  
  180.  
  181. scan.library/ArrangePanel                           scan.library/ArrangePanel
  182.  
  183.     NAME
  184.         ArrangePanel -- Arrange the ImageFX screens properly.
  185.  
  186.     SYNOPSIS
  187.         ArrangePanel ()
  188.  
  189.         void ArrangePanel ( void );
  190.  
  191.     FUNCTION
  192.         Arrange all of the screens that ImageFX uses such that they are
  193.         displayed properly.  Normally one would call this function right after
  194.         opening a screen of your own, so that the menu and possibly the
  195.         palette screens are shown over the bottom properly.  You should always
  196.         call this function instead of doing it yourself, for various reasons.
  197.  
  198.         Note however, that under V39, any screens you open yourself will
  199.         always appear in front of all ImageFX screens, unless you take
  200.         steps to attach the new screen to the ImageFX screens, like this:
  201.  
  202.            YourScreen = OpenScreenTags(NULL,
  203.                                        SA_Parent, ScanBase->sb_vScreen,
  204.                                        ....
  205.                                        TAG_END);
  206.            ArrangePanel();
  207.  
  208.     INPUTS
  209.         None.
  210.  
  211.     RESULTS
  212.         None.
  213.  
  214.     EXAMPLE
  215.  
  216.     NOTES
  217.  
  218.     BUGS
  219.  
  220.     SEE ALSO
  221.  
  222.  
  223. scan.library/Bar
  224.  
  225.     NAME
  226.         Bar - Increment status bar display.
  227.  
  228.     SYNOPSIS
  229.         cancelled = Bar ( iteration );
  230.         D0.L              D0.L
  231.  
  232.         int Bar ( int );
  233.  
  234.     FUNCTION
  235.         Calculates the status bar scale to show the given iteration
  236.         count.
  237.  
  238.     INPUTS
  239.         iteration -- The current iteration of the operation.  For
  240.             example, while loading a file you would call
  241.             Bar() for each scanline and pass the line number.
  242.  
  243.     RESULT
  244.         cancelled -- If you specified that there should be a Cancel
  245.             gadget with the BeginBar() function, then if
  246.             the user clicks that Cancel you will get a
  247.             non-zero result from Bar().  Otherwise, a
  248.             zero result means to continue the operation.
  249.  
  250.     EXAMPLE
  251.         BeginBar ("Chugging", 57, TRUE);
  252.         for (i = 0; i < 57; i++) {
  253.             if (Bar(i)) {
  254.                 Errorf ("You dope, you cancelled me!");
  255.                 break;
  256.             }
  257.             /* perform some calculation here */
  258.         }
  259.         EndBar(NULL);
  260.  
  261.     NOTES
  262.  
  263.     BUGS
  264.  
  265.     SEE ALSO
  266.         scan.library/BeginBar,scan.library/EndBar
  267.  
  268.  
  269. scan.library/BClose                                       scan.library/BClose
  270.  
  271.     NAME
  272.         BClose -- Close a buffered file.
  273.  
  274.     SYNOPSIS
  275.         BClose ( handle );
  276.                  A0
  277.  
  278.         void BClose ( struct BIO * );
  279.  
  280.     FUNCTION
  281.         Closes a buffered file previously opened with BOpen.
  282.  
  283.     INPUTS
  284.         handle -- file handle as returned by BOpen.
  285.  
  286.     RESULTS
  287.         None.
  288.  
  289.     EXAMPLE
  290.  
  291.     NOTES
  292.  
  293.     BUGS
  294.  
  295.     SEE ALSO
  296.         scan.library/BOpen
  297.  
  298.  
  299. scan.library/BeginBar
  300.  
  301.     NAME
  302.         BeginBar - Start a status bar operation.
  303.  
  304.     SYNOPSIS
  305.         BeginBar ( title, maxvalue, abortable );
  306.                    A0     D0.L      D1.L
  307.  
  308.         void BeginBar (char *, int, BOOL)
  309.  
  310.     FUNCTION
  311.         Initializes the status bar in preparation for a long operation.
  312.         Also displays the busy pointer, and prevents the user from
  313.         selecting gadgets on the menu panel.  Note that you MUST call
  314.         EndBar() to get back to normal operations; if you exit without
  315.         calling EndBar(), the user will not be able to do anything as
  316.         all the gadget input will be locked.
  317.  
  318.     INPUTS
  319.         title -- The title to display for the operation.  This
  320.             should be kepts as short as possible (10 characters
  321.             or so), as there is not a lot of room to display this.
  322.  
  323.         maxvalue -- The total number of iterations expected in the
  324.             operation.  For example, if you were loading a
  325.             file you would place the expected number of rows here.
  326.  
  327.         abortable -- If TRUE, a Cancel gadget will be presented to
  328.             the user.  Otherwise, the operation is non-stoppable.
  329.  
  330.     RESULT
  331.         None.
  332.  
  333.     EXAMPLE
  334.         See scan.library/Bar.
  335.  
  336.     NOTES
  337.  
  338.     BUGS
  339.  
  340.     SEE ALSO
  341.         scan.library/Bar,scan.library/EndBar
  342.  
  343.  
  344. scan.library/BFlush                                       scan.library/BFlush
  345.  
  346.     NAME
  347.         BFlush -- Flush current buffer to disk.
  348.  
  349.     SYNOPSIS
  350.         BFlush ( handle );
  351.                  A0
  352.  
  353.         void BFlush ( struct BIO * );
  354.  
  355.     FUNCTION
  356.         For a MODE_NEWFILE buffered file, flush the contents of the buffer to
  357.         disk.  For a read file, this function does nothing.
  358.  
  359.     INPUTS
  360.         handle -- file handle as returned by BOpen.
  361.  
  362.     RESULTS
  363.         None.
  364.  
  365.     EXAMPLE
  366.  
  367.     NOTES
  368.  
  369.     BUGS
  370.  
  371.     SEE ALSO
  372.  
  373.  
  374. scan.library/BGetc                                         scan.library/BGetc
  375.  
  376.     NAME
  377.         BGetc -- Read a character from buffered file.
  378.  
  379.     SYNOPSIS
  380.         character = BGetc ( handle );
  381.         D0.L                A0
  382.  
  383.         int BGetc ( struct BIO * );
  384.  
  385.     FUNCTION
  386.         Read the next available character from the given buffered file.  The
  387.         file handle must have been opened by BOpen as MODE_OLDFILE.
  388.  
  389.     INPUTS
  390.         handle -- file handle as returned by BOpen.
  391.  
  392.     RESULTS
  393.         character -- character that was read, or -1 on failure (eg. disk
  394.             error).
  395.  
  396.     EXAMPLE
  397.  
  398.     NOTES
  399.  
  400.     BUGS
  401.  
  402.     SEE ALSO
  403.  
  404.  
  405. scan.library/BGets                                         scan.library/BGets
  406.  
  407.     NAME
  408.         BGets -- Read a string from a buffered file.
  409.  
  410.     SYNOPSIS
  411.         count = BGets ( handle, buffer, maxlength );
  412.         D0.L            A0      A1      D0.L
  413.  
  414.         int BGets ( struct BIO *, UBYTE *, int );
  415.  
  416.     FUNCTION
  417.         Read from the given buffered file until the next newline.  The newline
  418.         is NOT stripped.  The file handle must have been opened by BOpen as
  419.         MODE_OLDFILE.
  420.  
  421.     INPUTS
  422.         handle -- file handle as returned by BOpen.
  423.  
  424.         buffer -- buffer into which to read the characters.
  425.  
  426.         maxlength -- maximum number of characters to read.
  427.  
  428.     RESULTS
  429.         count -- number of characters actually read.
  430.  
  431.     EXAMPLE
  432.  
  433.     NOTES
  434.  
  435.     BUGS
  436.  
  437.     SEE ALSO
  438.  
  439.  
  440. scan.library/BOpen                                         scan.library/BOpen
  441.  
  442.     NAME
  443.         BOpen -- Open a file for buffered reading or writing.
  444.  
  445.     SYNOPSIS
  446.         handle = BOpen ( filename, accessmode, bufsize );
  447.         D0.L             A0        D0.L        D1.L
  448.  
  449.         struct BIO *BOpen ( char *, ULONG, ULONG );
  450.  
  451.     FUNCTION
  452.         Open a file for buffered access.
  453.  
  454.     INPUTS
  455.         filename -- name of file to open.
  456.  
  457.         accessmode -- MODE_OLDFILE for reading or MODE_NEWFILE for writing.
  458.  
  459.         bufsize -- size of buffer for reading or writing.  If 0, then a
  460.             default value will be used.
  461.  
  462.     RESULTS
  463.         handle -- handle for subsequent access.  Do not attempt to examine the
  464.             contents of this structure.
  465.  
  466.     EXAMPLE
  467.  
  468.     NOTES
  469.  
  470.     BUGS
  471.  
  472.     SEE ALSO
  473.         scan.library/BClose
  474.  
  475.  
  476. scan.library/BPutc                                         scan.library/BPutc
  477.  
  478.     NAME
  479.         BPutc -- Write a character to buffered file.
  480.  
  481.     SYNOPSIS
  482.         success = BPutc ( handle, character );
  483.         D0.L              A0      D0.B
  484.  
  485.     FUNCTION
  486.         Write a single (unsigned) character to the given buffered file.  The
  487.         file handle must have been opened by BOpen as MODE_NEWFILE.
  488.  
  489.     INPUTS
  490.         handle -- file handle as returned by BOpen.
  491.  
  492.         character -- byte to write to the file.
  493.  
  494.     RESULTS
  495.         success -- TRUE if the character was sucessfully written, or FALSE if
  496.             something went wrong (eg. disk error).
  497.  
  498.     EXAMPLE
  499.  
  500.     NOTES
  501.  
  502.     BUGS
  503.  
  504.     SEE ALSO
  505.  
  506.  
  507. scan.library/BPuts                                         scan.library/BPuts
  508.  
  509.     NAME
  510.         BPuts -- Write a string to a buffered file.
  511.  
  512.     SYNOPSIS
  513.         success = BPuts ( handle, string );
  514.         D0.L              A0      A1
  515.  
  516.         BOOL BPuts ( struct BIO *, UBYTE * );
  517.  
  518.     FUNCTION
  519.         Write a null-terminated string to the given buffered file.  The
  520.         file handle must have been opened by BOpen as MODE_NEWFILE.  A newline
  521.         will be appended to the string when written to the file.
  522.  
  523.     INPUTS
  524.         handle -- file handle as returned by BOpen.
  525.  
  526.         string -- null-terminated string to write to the file.  A newline will
  527.             be appended.
  528.  
  529.     RESULTS
  530.         success -- TRUE if the string was sucessfully written, or FALSE if
  531.             something went wrong (eg. disk error).
  532.  
  533.     EXAMPLE
  534.  
  535.     NOTES
  536.  
  537.     BUGS
  538.  
  539.     SEE ALSO
  540.  
  541.  
  542. scan.library/BRead                                         scan.library/BRead
  543.  
  544.     NAME
  545.         BRead -- Read a block of characters from a buffered file.
  546.  
  547.     SYNOPSIS
  548.         count = BRead ( handle, buffer, length );
  549.         D0.L            A0      A1      D0.L
  550.  
  551.         int BRead ( struct BIO *, UBYTE *, int );
  552.  
  553.     FUNCTION
  554.         Read a fixed number of characters from a buffered file.  The
  555.         file handle must have been opened by BOpen as MODE_OLDFILE.
  556.  
  557.     INPUTS
  558.         handle -- file handle as returned by BOpen.
  559.  
  560.         buffer -- pointer to where to store read characters.
  561.  
  562.         length -- number of characters to read.
  563.  
  564.     RESULTS
  565.         count -- number of characters actually read from the file, or -1 on
  566.             failure (eg. disk error).
  567.  
  568.     EXAMPLE
  569.  
  570.     NOTES
  571.  
  572.     BUGS
  573.  
  574.     SEE ALSO
  575.  
  576.  
  577. scan.library/BSeek                                         scan.library/BSeek
  578.  
  579.     NAME
  580.         BSeek -- Seek to a file position within a buffered file.
  581.  
  582.     SYNOPSIS
  583.         oldposition = BSeek ( handle, offset, from );
  584.         D0.L                  A0      D0.L    D1.L
  585.  
  586.         int BSeek ( struct BIO *, int, int );
  587.  
  588.     FUNCTION
  589.         Seek to a specific file position in a way compatible with buffered
  590.         files.
  591.  
  592.     INPUTS
  593.         handle -- file handle as returned by BOpen.
  594.  
  595.         offset -- new file position.
  596.  
  597.         from -- where to seek from, OFFSET_BEGINNING, OFFSET_CURRENT, or
  598.             OFFSET_END.
  599.  
  600.     RESULTS
  601.         oldposition -- previous file position.
  602.  
  603.     EXAMPLE
  604.  
  605.     NOTES
  606.  
  607.     BUGS
  608.  
  609.     SEE ALSO
  610.  
  611.  
  612. scan.library/BWrite                                       scan.library/BWrite
  613.  
  614.     NAME
  615.         BWrite -- Write a block of characters to a buffered file.
  616.  
  617.     SYNOPSIS
  618.         count = BWrite ( handle, buffer, length );
  619.         D0.L             A0      A1      D0.L
  620.  
  621.         int BWrite ( struct BIO *, UBYTE *, int );
  622.  
  623.     FUNCTION
  624.         Write a fixed number of characters to a buffered file.  The
  625.         file handle must have been opened by BOpen as MODE_NEWFILE.
  626.  
  627.     INPUTS
  628.         handle -- file handle as returned by BOpen.
  629.  
  630.         buffer -- pointer to characters to write.
  631.  
  632.         length -- number of characters to write.
  633.  
  634.     RESULTS
  635.         count -- number of characters actually written to the file, or -1 on
  636.             failure (eg. disk error).
  637.  
  638.     EXAMPLE
  639.  
  640.     NOTES
  641.  
  642.     BUGS
  643.  
  644.     SEE ALSO
  645.  
  646.  
  647. scan.library/ClearBitMap                             scan.library/ClearBitMap
  648.  
  649.     NAME
  650.         ClearBitMap -- Clear the contents of a BitMap.
  651.  
  652.     SYNOPSIS
  653.         ClearBitMap ( bitmap );
  654.                       A0
  655.  
  656.         void ClearBitMap ( struct BitMap * );
  657.  
  658.     FUNCTION
  659.         Clears the bitplane memory of the given bitmap.  The bitplanes may be
  660.         in chip memory or fast memory.
  661.  
  662.     INPUTS
  663.         bitmap -- pointer to a BitMap structure.
  664.  
  665.     RESULTS
  666.         None.
  667.  
  668.     EXAMPLE
  669.  
  670.     NOTES
  671.  
  672.     BUGS
  673.  
  674.     SEE ALSO
  675.  
  676.  
  677. scan.library/DeleteBitMap                           scan.library/DeleteBitMap
  678.  
  679.     NAME
  680.         DeleteBitMap -- Deallocate a bitmap structure.
  681.  
  682.     SYNOPSIS
  683.         DeleteBitMap ( bitmap );
  684.                        A0
  685.  
  686.         void DeleteBitMap ( struct BitMap * );
  687.  
  688.     FUNCTION
  689.         Frees the bitplane memory and BitMap structure of the given bitmap.
  690.         Dimensions of the bitmap are obtained from the BitMap structure
  691.         itself.  Only use this function on BitMaps obtained with the
  692.         AllocChipBitMap() or AllocFastBitMap() functions.
  693.  
  694.     INPUTS
  695.         bitmap -- pointer to BitMap to free.
  696.  
  697.     RESULTS
  698.         None.
  699.  
  700.     EXAMPLE
  701.  
  702.     NOTES
  703.         Uses the new graphics.library FreeBitMap() function under V39.
  704.  
  705.     BUGS
  706.  
  707.     SEE ALSO
  708.  
  709.  
  710. scan.library/EasyProcess                             scan.library/EasyProcess
  711.  
  712.     NAME
  713.         EasyProcess -- Perform a simple 1:1 effect on an ImageFX buffer.
  714.  
  715.     SYNOPSIS
  716.         success = EasyProcess ( title, color_callback, grey_callback );
  717.         D0.L                    A0     A1              A2
  718.  
  719.         BOOL EasyProcess ( char *, void (*color_callback)(),
  720.                             void (*grey_callback)() );
  721.  
  722.     FUNCTION
  723.         Perform a simple affect on the user's currently selected region (main
  724.         buffer, brush, or region thereof).  Regional information, feathering,
  725.         and other factors will affect the operation.  You should try to use
  726.         this function if possible, as it does a great deal of work for you.
  727.  
  728.     INPUTS
  729.         title -- title to place in status bar while in progress.
  730.  
  731.         color_callback -- callback function which actually modifies color
  732.             pixels.  It's prototype is:
  733.  
  734.                 void color_callback (UBYTE *redptr, UBYTE *grnptr,
  735.                                      UBYTE *bluptr, short x, short y);
  736.  
  737.             Where:
  738.                 redptr -- pointer to current red pixel to be modified.
  739.                 grnptr -- pointer to current green pixel to be modified.
  740.                 bluptr -- pointer to current blue pixel to be modified.
  741.                 x -- current horizontal pixel location.
  742.                 y -- current vertical pixel location.
  743.  
  744.         grey_callback -- callback function which actually modifies grey
  745.             pixels.  It's prototype is:
  746.  
  747.                 void grey_callback (UBYTE *greyptr, short x, short y);
  748.  
  749.             Where:
  750.                 greyptr -- pointer to current grey pixel to be modified.
  751.                 x -- current horizontal pixel location.
  752.                 y -- current vertical pixel location.
  753.  
  754.             Arguments are passed on the stack.  You must make sure to restore
  755.             A4 in your callback functions if you are using small data model!
  756.  
  757.             EasyProcess() will decide whether to use the color or greyscale
  758.             callback function, based on the image it is working on.
  759.  
  760.     RESULTS
  761.         success -- TRUE if the process was successful, FALSE on failure.
  762.  
  763.     EXAMPLE
  764.         /* A simple color negative effect */
  765.  
  766.         void __saveds colorback (UBYTE *r, UBYTE *g, UBYTE *b,
  767.                                  short x, short y)
  768.         {
  769.             *r = 255 - *r;
  770.             *g = 255 - *g;
  771.             *b = 255 - *b;
  772.         }
  773.  
  774.         void __saveds greyback (UBYTE *g, short x, short y)
  775.         {
  776.             *g = 255 - *g;
  777.         }
  778.  
  779.         void DoEffect (void)
  780.         {
  781.             EasyProcess("Negative", colorback, greyback);
  782.         }
  783.  
  784.     NOTES
  785.         This should not be used to do geometric or translational effects on a
  786.         buffer (ie. where pixel positions are moved).  This is only good for
  787.         doing color effects.
  788.  
  789.     BUGS
  790.  
  791.     SEE ALSO
  792.  
  793.  
  794. scan.library/EndBar
  795.  
  796.     NAME
  797.         EndBar - End a status bar operation.
  798.  
  799.     SYNOPSIS
  800.         EndBar ( dummy );
  801.  
  802.         void EndBar (void *);
  803.  
  804.     FUNCTION
  805.         This cleans up and ends a status bar operation.  It clears
  806.         the busy pointer and allows the user to select gadgets in the
  807.         menu panel again.
  808.  
  809.     INPUTS
  810.         None, really.  There used to be an argument, but it has been
  811.         removed.  You should pass NULL as the argument.
  812.  
  813.     RESULT
  814.         None.
  815.  
  816.     EXAMPLE
  817.         See scan.library/Bar.
  818.  
  819.     NOTES
  820.  
  821.     BUGS
  822.         None known.
  823.  
  824.     SEE ALSO
  825.         scan.library/BeginBar,scan.library/Bar
  826.  
  827.  
  828. scan.library/Error
  829.  
  830.     NAME
  831.         Error - Show error message for last generated error.
  832.  
  833.     SYNOPSIS
  834.         Error ();
  835.  
  836.         void Error ( void );
  837.  
  838.     FUNCTION
  839.         Will display a requester to the user showing the text for
  840.         the last error generated.  This function does not return
  841.         until the user clicks Okay.
  842.  
  843.     INPUTS
  844.         None.
  845.  
  846.     RESULT
  847.         None.
  848.  
  849.     EXAMPLE
  850.  
  851.         buffer = AllocBuffer (NULL, 320, 200, 1, 8, 0);
  852.         if (buffer == NULL) {   /* can't get buffer? */
  853.             Error();            /* tell what happend */
  854.             return;
  855.         }
  856.  
  857.     NOTES
  858.  
  859.     BUGS
  860.  
  861.     SEE ALSO
  862.         scan.library/Errorf,scan.library/SetError
  863.  
  864.  
  865. scan.library/FreeBuffer                               scan.library/FreeBuffer
  866.  
  867.     NAME
  868.         FreeBuffer -- Free ImageFX's main buffer.
  869.  
  870.     SYNOPSIS
  871.         FreeBuffer ();
  872.  
  873.         void FreeBuffer ( void );
  874.  
  875.     FUNCTION
  876.         Frees the current main buffer, by calling KillBuffer().
  877.  
  878.     INPUTS
  879.         None.
  880.  
  881.     RESULTS
  882.         None.
  883.  
  884.     EXAMPLE
  885.  
  886.     NOTES
  887.  
  888.     BUGS
  889.  
  890.     SEE ALSO
  891.  
  892.  
  893. scan.library/GetBufLine
  894.  
  895.     NAME
  896.         GetBufLine - Get pointer(s) to a Buffer scanline.
  897.  
  898.     SYNOPSIS
  899.         success = GetBufLine ( buffer, redptr, grnptr, bluptr, row );
  900.         D0.L                   A0      A1      A2      A3      D0.W
  901.  
  902.         int GetBufLine ( struct Buffer *, UBYTE **, UBYTE **, UBYTE **,
  903.                          short );
  904.  
  905.     FUNCTION
  906.         Fills in the supplied pointers with pointers to the image data
  907.         for a Buffer.  You should ONLY reference a buffer by using
  908.         this function, as there is more work than meets the eye for
  909.         a buffer maintained on disk.
  910.  
  911.     INPUTS
  912.         buffer -- Pointer to a Buffer obtained via. ObtainBuffer().
  913.  
  914.         redptr -- Where to store Red scanline pointer.
  915.  
  916.         grnptr -- Where to store Green scanline pointer.
  917.  
  918.         bluptr -- Where to store Blue scanline pointer.
  919.  
  920.         row -- Which scanline to retreive, starting from 0 at the
  921.             topmost scanline.
  922.  
  923.     RESULT
  924.         success -- Non-zero if the command was successful.  It can
  925.             only fail if the buffer is maintained on disk and
  926.             enough memory cannot be allocated to read the
  927.             scanline.  A rare occurance, but one worth checking for.
  928.  
  929.     EXAMPLE
  930.  
  931.     NOTES
  932.         For a greyscale buffer, "grnptr" and "bluptr" are set
  933.         to point to the same data as "redptr".
  934.  
  935.     BUGS
  936.  
  937.     SEE ALSO
  938.         scan.library/PutBufLine,scan.library/PutNewBufLine
  939.  
  940.  
  941. scan.library/GetError                                   scan.library/GetError
  942.  
  943.     NAME
  944.         GetError -- Retreive secondary error code.
  945.  
  946.     SYNOPSIS
  947.         error = GetError ();
  948.         D0.L
  949.  
  950.         ULONG GetError ( void );
  951.  
  952.     FUNCTION
  953.         Returns the current secondary error code, as set by a previous call to
  954.         SetError().
  955.  
  956.     INPUTS
  957.         None.
  958.  
  959.     RESULTS
  960.         error -- current error code.  See "scan/errors.h".
  961.  
  962.     EXAMPLE
  963.  
  964.     NOTES
  965.  
  966.     BUGS
  967.  
  968.     SEE ALSO
  969.  
  970.  
  971. scan.library/HidePanel                                 scan.library/HidePanel
  972.  
  973.     NAME
  974.         HidePanel -- Push the menu screen to the back.
  975.  
  976.     SYNOPSIS
  977.         HidePanel ()
  978.  
  979.         void HidePanel (void);
  980.  
  981.     FUNCTION
  982.         Pushes the menu screen ("panel") to the back, if it is not already
  983.         hidden.
  984.  
  985.     INPUTS
  986.         None.
  987.  
  988.     RESULTS
  989.         None.
  990.  
  991.     EXAMPLE
  992.  
  993.     NOTES
  994.  
  995.     BUGS
  996.  
  997.     SEE ALSO
  998.         scan.library/ShowPanel,scan.library/TogglePanel
  999.  
  1000.  
  1001. scan.library/InitBuffer                               scan.library/InitBuffer
  1002.  
  1003.     NAME
  1004.         InitBuffer -- Create ImageFX main buffer.
  1005.  
  1006.     SYNOPSIS
  1007.         InitBuffer ( name, width, height, depth, bits, flags );
  1008.                      A0    D0.W   D1.W    D2.W   D3.W  D4.W
  1009.  
  1010.         void InitBuffer ( char *, short, short, short, short, short );
  1011.  
  1012.     FUNCTION
  1013.         Creates a main image buffer, deleting the old one first if it exists.
  1014.         This function is otherwise identical to AllocBuffer().
  1015.  
  1016.     INPUTS
  1017.         See AllocBuffer().
  1018.  
  1019.     RESULTS
  1020.         None.
  1021.  
  1022.     EXAMPLE
  1023.  
  1024.     NOTES
  1025.         You can tell whether the call was succesful or not by checking the
  1026.         result of GetError(), or by doing an ObtainBuffer(0).
  1027.  
  1028.     BUGS
  1029.  
  1030.     SEE ALSO
  1031.  
  1032.  
  1033. scan.library/IntegerRequest                       scan.library/IntegerRequest
  1034.  
  1035.     NAME
  1036.         IntegerRequest -- Present a slider gadget requester to the user.
  1037.  
  1038.     SYNOPSIS
  1039.         result = IntegerRequest ( title, low, high, initial );
  1040.         D0.L                      A0     D0.L D1.L  D2.L
  1041.  
  1042.         LONG IntegerRequest ( char *, LONG, LONG, LONG );
  1043.  
  1044.     FUNCTION
  1045.         Display a requester containing a slider gadget to the user.  The user
  1046.         must select a value or cancel before this function will return.
  1047.  
  1048.     INPUTS
  1049.         title -- Title of the requester.
  1050.  
  1051.         low -- Lowest value that can be selected with the slider.
  1052.  
  1053.         high -- Highest value that can be selected with the slider.
  1054.  
  1055.         initial -- Initial value of the slider.
  1056.  
  1057.     RESULTS
  1058.         result -- value selected by the user.  If the value is less than the
  1059.             lowest possible value, then the user cancelled the requester.
  1060.  
  1061.     EXAMPLE
  1062.         value = IntegerRequest("Pick a number:", -10, 10, 0);
  1063.         if (value < -10) Errorf("Hey, you can't cancel me!");
  1064.  
  1065.     NOTES
  1066.  
  1067.     BUGS
  1068.  
  1069.     SEE ALSO
  1070.  
  1071.  
  1072. scan.library/KillBuffer
  1073.  
  1074.     NAME
  1075.         KillBuffer - Deallocate a Buffer structure.
  1076.  
  1077.     SYNOPSIS
  1078.         KillBuffer ( buffer );
  1079.                      A0
  1080.  
  1081.         void KillBuffer ( struct Buffer * );
  1082.  
  1083.     FUNCTION
  1084.         Deallocates all the memory used in a Buffer structure,
  1085.         including image data memory, structure memory, and anything
  1086.         in between.  The buffer no longer exists when this function
  1087.         returns.
  1088.  
  1089.     INPUTS
  1090.         buffer -- Pointer to a Buffer structure.
  1091.  
  1092.     RESULT
  1093.         None.
  1094.  
  1095.     EXAMPLE
  1096.  
  1097.     NOTES
  1098.  
  1099.     BUGS
  1100.  
  1101.     SEE ALSO
  1102.         scan.library/AllocBuffer,scan/buf.h
  1103.  
  1104.  
  1105. scan.library/NewGetFile                               scan.library/NewGetFile
  1106.  
  1107.     NAME
  1108.         NewGetFile -- Open a file requester.
  1109.  
  1110.     SYNOPSIS
  1111.         file = NewGetFile ( fileinfo, title, flags );
  1112.         D0.L                A0        A1     D0.L
  1113.  
  1114.         char *NewGetFile ( struct FileInfo *, char *, ULONG );
  1115.  
  1116.     FUNCTION
  1117.         Present a file requester from which the user may select a file or
  1118.         directory.  Uses the user's preferred file requester (as set in
  1119.         Prefs).
  1120.  
  1121.     INPUTS
  1122.         fileinfo -- pointer to a FileInfo structure, describing how to open
  1123.             the file requester.  You should fill in the following fields (do
  1124.             not touch any others):
  1125.  
  1126.                 Dir:
  1127.                     Directory where file requester should open.
  1128.  
  1129.                 File:
  1130.                     Default filename.
  1131.  
  1132.                 Pattern:
  1133.                     Filename pattern.
  1134.  
  1135.                 Screen:
  1136.                     Pointer to a custom screen on which to open.
  1137.  
  1138.         title -- title of the file requester.
  1139.  
  1140.         flags -- various flags for the file requester.
  1141.  
  1142.                 FI_SAVE:
  1143.                     Set when this requester is a save action.
  1144.  
  1145.                 FI_DIRONLY:
  1146.                     Only allow selection of a directory.
  1147.  
  1148.                 FI_SCREEN:
  1149.                     Force requester to open on the screen specified by
  1150.                     FileInfo.Screen.
  1151.  
  1152.     RESULTS
  1153.         file -- complete path to filename chosen by the user if successful, or
  1154.             FALSE on failure.  The FileInfo structure will also be updated to
  1155.             reflect the user's selection.
  1156.  
  1157.     EXAMPLE
  1158.  
  1159.     NOTES
  1160.  
  1161.     BUGS
  1162.  
  1163.     SEE ALSO
  1164.  
  1165.  
  1166. scan.library/ObtainBuffer
  1167.  
  1168.     NAME
  1169.         ObtainBuffer - Get a pointer to an image Buffer.
  1170.  
  1171.     SYNOPSIS
  1172.         buffer = ObtainBuffer ( which );
  1173.         D0.L                    D0.L
  1174.  
  1175.         struct Buffer *ObtainBuffer ( int );
  1176.  
  1177.     FUNCTION
  1178.         Returns a pointer to one of the image buffers in use
  1179.         within ImageFX.  You should ALWAYS use this function to get
  1180.         at these buffers, as there is special initialization when the
  1181.         buffer is actually maintained on disk.
  1182.  
  1183.     INPUTS
  1184.         which -- Which buffer to get:
  1185.  
  1186.                     0 = Main buffer
  1187.                     1 = Swap buffer
  1188.                     2 = Alpha channel
  1189.                     3 = Undo buffer
  1190.                     4 = Brush buffer
  1191.  
  1192.     RESULT
  1193.         buffer -- A pointer to the Buffer or NULL if it could not
  1194.             be obtained for some reason.  A typical reason for
  1195.             failure is that the given buffer does not exist.
  1196.  
  1197.     EXAMPLE
  1198.  
  1199.     NOTES
  1200.         You don't get a copy of the buffer, you get the actual pointer
  1201.         to the actual buffer, so be careful which fields you play with.
  1202.         A lot of the fields in the Buffer structure are for internal
  1203.         use only.
  1204.  
  1205.         Currently, two tasks can ObtainBuffer() the same buffer and
  1206.         be successful.  This may change in the future.  For now, try
  1207.         not to nest your ObtainBuffer()/ReleaseBuffer() calls.
  1208.  
  1209.         Remember to ReleaseBuffer() the buffer when you are done.
  1210.  
  1211.     BUGS
  1212.         None known.
  1213.  
  1214.     SEE ALSO
  1215.         scan.library/ReleaseBuffer,scan/buf.h
  1216.  
  1217.  
  1218. scan.library/ParseCommand                           scan.library/ParseCommand
  1219.  
  1220.     NAME
  1221.         ParseCommand -- Parse an ImageFX command string.
  1222.  
  1223.     SYNOPSIS
  1224.         result = ParseCommand ( commandstring, message );
  1225.         D0.L                    A0             A1
  1226.  
  1227.         int ParseCommand ( char *, struct RexxMsg * );
  1228.  
  1229.     FUNCTION
  1230.         Passes a string of commands to ImageFX for it to execute.  This
  1231.         function does not return until the commands are completed (or
  1232.         aborted).  The string may contain more than one command if each is
  1233.         separated by a semi-colon (;).
  1234.  
  1235.     INPUTS
  1236.         commandstring -- pointer to string of commands to execute.
  1237.  
  1238.         message -- invoking Arexx message, used to set result codes.  You
  1239.             should pass NULL.
  1240.  
  1241.     RESULTS
  1242.         result -- result code from the commands, 0 for success or non-zero on
  1243.             failure.
  1244.  
  1245.     EXAMPLE
  1246.         ParseCommand("Negative; Swap; Color2Grey Luma", NULL);
  1247.  
  1248.     NOTES
  1249.         See the ImageFX manual chapter on Arexx commands for details of the
  1250.         commands that ImageFX understands.
  1251.  
  1252.     BUGS
  1253.  
  1254.     SEE ALSO
  1255.  
  1256.  
  1257. scan.library/PutBufLine
  1258.  
  1259.     NAME
  1260.         PutBufLine - Restore last scanline read to a Buffer.
  1261.  
  1262.     SYNOPSIS
  1263.         success = PutBufLine ( buffer );
  1264.         D0.L                   A0
  1265.  
  1266.         int PutBufLine ( struct Buffer *buffer );
  1267.  
  1268.     FUNCTION
  1269.         Restores to the given buffer the last scanline read with the
  1270.         GetBufLine() function.  This function must be called if any
  1271.         changes are made to the scanline.  You *MUST* call GetBufLine()
  1272.         before calling this function.
  1273.  
  1274.     INPUTS
  1275.         buffer -- Pointer to a Buffer structure as returned by ObtainBuffer().
  1276.  
  1277.     RESULT
  1278.         success -- Non-zero if successful.
  1279.  
  1280.     EXAMPLE
  1281.         buffer = ObtainBuffer(0);
  1282.         if (buffer) {
  1283.             for (row = 0; row < buffer->Height; row++) {
  1284.                 GetBufLine (buffer, &red, &grn, &blu, row);
  1285.                 /* make some changes to the data */
  1286.                 PutBufLine (buffer);
  1287.             }
  1288.             ReleaseBuffer (buffer);
  1289.         }
  1290.  
  1291.     NOTES
  1292.         This function cannot currently fail.
  1293.  
  1294.         Not calling this function after making changes to a scanline will
  1295.         only become apparent when working on disk buffers.
  1296.  
  1297.     BUGS
  1298.  
  1299.     SEE ALSO
  1300.         scan.library/GetBufLine
  1301.  
  1302.  
  1303. scan.library/PutNewBufLine
  1304.  
  1305.     NAME
  1306.         PutNewBufLine - Store new image data into a buffer scanline.
  1307.  
  1308.     SYNOPSIS
  1309.         success = PutNewBufLine ( buffer, reddata, grndata, bludata, row );
  1310.         D0.L                      A0      A1       A2       A3       D0.W
  1311.  
  1312.         int PutNewBufLine ( struct Buffer *, UBYTE *, UBYTE *, UBYTE *,
  1313.                             short );
  1314.  
  1315.     FUNCTION
  1316.         Stores image data into a buffer at any arbitrary scanline.
  1317.         You do NOT need to call GetBufLine() beforehand.  The image
  1318.         data is copied, so you don't need to hold onto the data.
  1319.  
  1320.     INPUTS
  1321.         buffer -- Buffer structure as returned by ObtainBuffer().
  1322.  
  1323.         reddata -- Pointer to Red image data.
  1324.  
  1325.         grndata -- Pointer to Green image data.
  1326.  
  1327.         bludata -- Pointer to Blue image data.
  1328.  
  1329.         row -- Scanline to store the data, starting from 0.
  1330.  
  1331.     RESULT
  1332.         success -- Non-zero if successful.
  1333.  
  1334.     EXAMPLE
  1335.         buffer = ObtainBuffer(0);
  1336.         if (buffer) {
  1337.             for (row = 0; row < buffer->Height; row += 4) {
  1338.                 /* build a scanline of data */
  1339.                 PutNewBufLine (buffer, red, grn, blu, row);
  1340.             }
  1341.             ReleaseBuffer (buffer);
  1342.         }
  1343.  
  1344.     NOTES
  1345.         This function can only fail if the buffer is maintained on disk
  1346.         and memory could not be obtained to swap the relavant page into
  1347.         memory.
  1348.  
  1349.         When storing to a greyscale buffer, the Red pointer should point
  1350.         to the greyscale data.  The other two pointers are ignored.
  1351.  
  1352.     BUGS
  1353.  
  1354.     SEE ALSO
  1355.         scan.library/GetBufLine,scan.library/PutBufLine
  1356.  
  1357.  
  1358. scan.library/RedrawArea                               scan.library/RedrawArea
  1359.  
  1360.     NAME
  1361.         RedrawArea -- Redraw a portion of the main image buffer.
  1362.  
  1363.     SYNOPSIS
  1364.         RedrawArea ( left, top, right, bottom );
  1365.                      D0.L  D1.L D2.L   D3.L
  1366.  
  1367.         void RedrawArea ( int, int, int, int );
  1368.  
  1369.     FUNCTION
  1370.         Redraw only a portion of the current ImageFX main buffer.  If
  1371.         redrawing has been disabled (with the "Redraw Off" command),
  1372.         no update will take place, but the screen will be refreshed when
  1373.         redraw is turned back on.
  1374.  
  1375.         You should call this or the RedrawFull() function after you have made
  1376.         a modification to an image buffer.
  1377.  
  1378.     INPUTS
  1379.         left, top -- upper left corner of the area you want to redraw,
  1380.             measured in pixels.
  1381.  
  1382.         right, bottom -- bottom right corner of the area you want to redraw,
  1383.             measured in pixels.
  1384.  
  1385.     RESULTS
  1386.         None.
  1387.  
  1388.     EXAMPLE
  1389.  
  1390.     NOTES
  1391.  
  1392.     BUGS
  1393.  
  1394.     SEE ALSO
  1395.  
  1396.  
  1397. scan.library/RedrawFull                               scan.library/RedrawFull
  1398.  
  1399.     NAME
  1400.         RedrawFull -- Redraw main image buffer.
  1401.  
  1402.     SYNOPSIS
  1403.         RedrawFull ();
  1404.  
  1405.         void RedrawFull ( void );
  1406.  
  1407.     FUNCTION
  1408.         Redraw the current ImageFX main buffer.  If redrawing has been
  1409.         disabled (with the "Redraw Off" command), no update will take place,
  1410.         but the screen will be refreshed when redraw is turned back on.
  1411.  
  1412.         You should call this or the RedrawArea() function after you have made
  1413.         a modification to an image buffer.
  1414.  
  1415.     INPUTS
  1416.         None.
  1417.  
  1418.     RESULTS
  1419.         None.
  1420.  
  1421.     EXAMPLE
  1422.  
  1423.     NOTES
  1424.  
  1425.     BUGS
  1426.  
  1427.     SEE ALSO
  1428.         scan.library/RedrawArea
  1429.  
  1430.  
  1431. scan.library/ReleaseBuffer
  1432.  
  1433.     NAME
  1434.         ReleaseBuffer - Release a Buffer after you're finished.
  1435.  
  1436.     SYNOPSIS
  1437.         ReleaseBuffer ( buffer );
  1438.                         A0
  1439.  
  1440.         void ReleaseBuffer ( struct Buffer * );
  1441.  
  1442.     FUNCTION
  1443.         Releases a Buffer obtained with ObtainBuffer(), doing any
  1444.         cleanup necessary.  You should ALWAYS call this function
  1445.         when you are done with the Buffer, as there is special
  1446.         cleanup involved if the buffer is maintained on disk.
  1447.  
  1448.     INPUTS
  1449.         buffer -- Pointer to a Buffer structure obtained with
  1450.             the ObtainBuffer() structure.
  1451.  
  1452.     RESULT
  1453.         None.
  1454.  
  1455.     EXAMPLE
  1456.  
  1457.     NOTES
  1458.  
  1459.     BUGS
  1460.  
  1461.     SEE ALSO
  1462.         scan.library/ObtainBuffer,scan/buf.h
  1463.  
  1464.  
  1465. scan.library/ReplaceBuffer                         scan.library/ReplaceBuffer
  1466.  
  1467.     NAME
  1468.         ReplaceBuffer -- Replace the contents of one buffer with another.
  1469.  
  1470.     SYNOPSIS
  1471.         ReplaceBuffer ( oldBuf, newBuf );
  1472.                         A0      A1
  1473.  
  1474.         void ReplaceBuffer ( struct Buffer *, struct Buffer * );
  1475.  
  1476.     FUNCTION
  1477.         Replaces the image data of the old buffer with the image data of the
  1478.         new buffer.  The new buffer is then freed.
  1479.  
  1480.     INPUTS
  1481.         oldBuf -- pointer to Buffer to replace.
  1482.  
  1483.         newBuf -- pointer to Buffer with the image data that is to replace the
  1484.             old buffer.  This buffer will be freed when the function returns.
  1485.  
  1486.     RESULTS
  1487.         None.
  1488.  
  1489.     EXAMPLE
  1490.  
  1491.     NOTES
  1492.  
  1493.     BUGS
  1494.  
  1495.     SEE ALSO
  1496.  
  1497.  
  1498. scan.library/SaveUndo                                   scan.library/SaveUndo
  1499.  
  1500.     NAME
  1501.         SaveUndo -- Save an area of a buffer to the undo buffer.
  1502.  
  1503.     SYNOPSIS
  1504.         continue = SaveUndo ( buffer, left, top, width, height );
  1505.         D0.L                  A0      D0.W  D1.W D2.W   D3.W
  1506.  
  1507.         BOOL SaveUndo ( struct Buffer *, short, short, short, short );
  1508.  
  1509.     FUNCTION
  1510.         Stores a copy of the selected area of the buffer in the undo buffer.
  1511.         The previous contents of the undo buffer are lost.  Only enough memory
  1512.         to hold the requested area is allocated for the undo buffer, to keep
  1513.         memory useage to a minimum.
  1514.  
  1515.         Always use this function if you are about to permanently alter
  1516.         ImageFX's main buffer, to give the user a chance to change his mind.
  1517.  
  1518.     INPUTS
  1519.         buffer -- pointer to Buffer from which to save the data.  This will
  1520.             usually be either the main buffer or a brush.
  1521.  
  1522.         left, top -- upper left pixel coordinate of the area to save, starting
  1523.             from 0,0 at the upper left of the image.
  1524.  
  1525.         width, height -- pixel size of the area to save.
  1526.  
  1527.     RESULTS
  1528.         continue -- if there is not enough memory to save an undo buffer, the
  1529.             user will be asked if he would like to continue without one.  The
  1530.             results of that request are returned here.  TRUE means either
  1531.             there was enough memory or the user wants to continue, FALSE means
  1532.             the operation should be terminated.
  1533.  
  1534.     EXAMPLE
  1535.         if (buf = ObtainBuffer(0)) {
  1536.             if (SaveUndo(buf, 0, 0, buf->Width, buf->Height)) {
  1537.                 /* do something to entire image */
  1538.             }
  1539.             ReleaseBuffer(buf);
  1540.         }
  1541.  
  1542.     NOTES
  1543.  
  1544.     BUGS
  1545.  
  1546.     SEE ALSO
  1547.  
  1548.  
  1549. scan.library/SetError
  1550.  
  1551.     NAME
  1552.         SetError - Set secondary error code.
  1553.  
  1554.     SYNOPSIS
  1555.         SetError ( errorcode )
  1556.                    D0.L
  1557.  
  1558.         void SetError ( ULONG );
  1559.  
  1560.     FUNCTION
  1561.         Sets the secondary error code upon failure.  Normally, functions
  1562.         simply return a TRUE or FALSE for success or failure.  On
  1563.         failure, a person can look to the secondary error code to
  1564.         find more information about why a particular function failed.
  1565.         This presumes that the failing function puts some meaningful
  1566.         information in the secondary error code.
  1567.  
  1568.     INPUTS
  1569.         errorcode -- A code describing an error condition.  Use the codes
  1570.             defined in "scan/errors.h".  The ERR_UserCancel code will
  1571.             not generate a requester on failure, all others will.
  1572.  
  1573.     RESULT
  1574.         None.
  1575.  
  1576.     EXAMPLE
  1577.  
  1578.     NOTES
  1579.  
  1580.     BUGS
  1581.  
  1582.     SEE ALSO
  1583.         scan/errors.h
  1584.  
  1585.  
  1586. scan.library/ShowPanel                                 scan.library/ShowPanel
  1587.  
  1588.     NAME
  1589.         ShowPanel -- Bring the the menu screen to the front.
  1590.  
  1591.     SYNOPSIS
  1592.         ShowPanel ()
  1593.  
  1594.         void ShowPanel ( void );
  1595.  
  1596.     FUNCTION
  1597.         Bring the menu screen ("panel") to the front, if it is not already
  1598.         visible.  You should always use this function instead of
  1599.         ScreenToFront(pScreen) so that the palette screen is handled properly.
  1600.  
  1601.     INPUTS
  1602.  
  1603.     RESULTS
  1604.  
  1605.     EXAMPLE
  1606.  
  1607.     NOTES
  1608.  
  1609.     BUGS
  1610.  
  1611.     SEE ALSO
  1612.         scan.library/HidePanel,scan.library/TogglePanel
  1613.  
  1614.  
  1615. scan.library/ShowStatus
  1616.  
  1617.     NAME
  1618.         ShowStatus -- display buffer information on ImageFX menu.
  1619.  
  1620.     SYNOPSIS
  1621.         ShowStatus ( buffer )
  1622.                      A0
  1623.  
  1624.         void ShowStatus ( struct Buffer * )
  1625.  
  1626.     FUNCTION
  1627.         Updates the Image Scan information display (which shows
  1628.         the name of the current image and its width and height),
  1629.         updates the mode indicators and the channel gadgets.
  1630.  
  1631.     INPUTS
  1632.         buffer -- The buffer from which to get all the information
  1633.             to display.  If NULL, then the current main buffer information
  1634.             will be used.
  1635.  
  1636.     RESULT
  1637.         None.
  1638.  
  1639.     EXAMPLE
  1640.  
  1641.     NOTES
  1642.         The main purpose for this is for Loaders to display the
  1643.         width/height/etc. of the file they are loading while
  1644.         decoding the file, so the user knows what he is loading.
  1645.  
  1646.     BUGS
  1647.  
  1648.     SEE ALSO
  1649.  
  1650.  
  1651. scan.library/StringRequest                         scan.library/StringRequest
  1652.  
  1653.     NAME
  1654.         StringRequest -- Present a string gadget requester to the user.
  1655.  
  1656.     SYNOPSIS
  1657.         result = StringRequest ( title, initial );
  1658.         D0.L                     A0     A1
  1659.  
  1660.         char *StringRequest ( char *, char * );
  1661.  
  1662.     FUNCTION
  1663.         Displays a string gadget requester where the user may enter a text
  1664.         string.  The function does not return until the user enters a string
  1665.         or cancels.
  1666.  
  1667.     INPUTS
  1668.         title -- Title for the requester.
  1669.  
  1670.         initial -- Initial contents of the string gadget, may be NULL.
  1671.  
  1672.     RESULTS
  1673.         result -- pointer to the string the user entered or NULL if the user
  1674.             cancels the requester.  You should make a copy of the string as
  1675.             soon as possible, because the next call to StringRequest() will
  1676.             destroy it.
  1677.  
  1678.     EXAMPLE
  1679.  
  1680.     NOTES
  1681.  
  1682.     BUGS
  1683.  
  1684.     SEE ALSO
  1685.  
  1686.  
  1687. scan.library/TogglePanel                             scan.library/TogglePanel
  1688.  
  1689.     NAME
  1690.         TogglePanel -- Toggle the visibility of the menu screen.
  1691.  
  1692.     SYNOPSIS
  1693.         TogglePanel ()
  1694.  
  1695.         void TogglePanel ( void );
  1696.  
  1697.     FUNCTION
  1698.         Toggles the menu screen ("panel") in front or back of the other
  1699.         screens.  This is what happens in response to a right mouse button
  1700.         click.
  1701.  
  1702.     INPUTS
  1703.         None.
  1704.  
  1705.     RESULTS
  1706.         None.
  1707.  
  1708.     EXAMPLE
  1709.  
  1710.     NOTES
  1711.  
  1712.     BUGS
  1713.  
  1714.     SEE ALSO
  1715.         scan.library/HidePanel,scan.library/ShowPanel
  1716.  
  1717.  
  1718. scan.library/VBoolRequest                           scan.library/VBoolRequest
  1719.  
  1720.     NAME
  1721.         VBoolRequest -- Present boolean Okay/Cancel requester to user.
  1722.         BoolRequest -- varargs stub to VBoolRequest.
  1723.  
  1724.     SYNOPSIS
  1725.         result = VBoolRequest ( title, arglist );
  1726.         D0.L                    A0     A1
  1727.  
  1728.         BOOL VBoolRequest ( char *, ULONG * );
  1729.  
  1730.         result = BoolRequest ( title, ... );
  1731.  
  1732.         BOOL BoolRequest ( char *, ... );
  1733.  
  1734.     FUNCTION
  1735.         Display a boolean Okay/Cancel requester to the user.  The function
  1736.         does not return until the user presses either the Okay or Cancel
  1737.         gadgets.
  1738.  
  1739.     INPUTS
  1740.         title -- Title of the requester.  Can contain printf-style formatting
  1741.             information.
  1742.  
  1743.         arglist -- pointer to list of arguments used to format the title
  1744.             string.
  1745.  
  1746.     RESULTS
  1747.         result -- TRUE if user selected Okay, FALSE if he selected Cancel.
  1748.  
  1749.     EXAMPLE
  1750.  
  1751.     NOTES
  1752.         BoolRequest() is defined in "scan.lib".
  1753.  
  1754.     BUGS
  1755.  
  1756.     SEE ALSO
  1757.  
  1758.  
  1759. scan.library/VErrorf
  1760.  
  1761.     NAME
  1762.         VErrorf -- Display generic error message to user.
  1763.         Errorf -- varargs stub to VErrorf().
  1764.  
  1765.     SYNOPSIS
  1766.         VErrorf ( controlstring, arglistptr )
  1767.                   A0             A1
  1768.  
  1769.         void VErrorf (char *, LONG * );
  1770.  
  1771.         Errorf ( controlstring, firstArg, ... );
  1772.  
  1773.         void Errorf ( char *, ... );
  1774.  
  1775.     FUNCTION
  1776.         Displays a bit of text to the user as an error message.  The
  1777.         function does not return until the user clicks the Okay
  1778.         gadget in the requester.
  1779.  
  1780.     INPUTS
  1781.         controlstring -- A printf()-style formatting string.
  1782.  
  1783.         arglistptr -- pointer to a longword array of arguments to be formatted
  1784.             for display.
  1785.  
  1786.     RESULT
  1787.         None.
  1788.  
  1789.     EXAMPLE
  1790.         Errorf ("Your %ls didn't work on attempt #%ld!",
  1791.                     bean_string, attempt_number);
  1792.  
  1793.     NOTES
  1794.         Errorf() is defined in "scan.lib".
  1795.  
  1796.     BUGS
  1797.  
  1798.     SEE ALSO
  1799.         scan.library/Error
  1800.  
  1801.  
  1802. scan.library/VInfoRequest                           scan.library/VInfoRequest
  1803.  
  1804.     NAME
  1805.         VInfoRequest -- Display informational requester.
  1806.         InfoRequest -- varargs stub to VInfoRequest.
  1807.  
  1808.     SYNOPSIS
  1809.         VInfoRequest ( controlstring, arglistptr )
  1810.                        A0             A1
  1811.  
  1812.         void VInfoRequest (char *, ULONG * );
  1813.  
  1814.         InfoRequest ( controlstring, firstArg, ... );
  1815.  
  1816.         void InfoRequest ( char *, ... );
  1817.  
  1818.  
  1819.     FUNCTION
  1820.         Display a simple 1-line informational requester.  The user must select
  1821.         the Okay gadget to proceed.
  1822.  
  1823.     INPUTS
  1824.         controlstring -- A printf()-style formatting string.
  1825.  
  1826.         arglistptr -- pointer to a longword array of arguments to be formatted
  1827.             for display.
  1828.  
  1829.     RESULTS
  1830.         None.
  1831.  
  1832.     EXAMPLE
  1833.  
  1834.     NOTES
  1835.         InfoRequest() is defined in "scan.lib".
  1836.  
  1837.     BUGS
  1838.  
  1839.     SEE ALSO
  1840.  
  1841.  
  1842. scan.library/zzzzzz
  1843.  
  1844. (That's so my autodoc-insertion macro works properly...)
  1845. RedrawArea
  1846.